summary

closes #322.

a long kb.list_pending forces a reviewer to reconstruct, per proposal,
whether the claim fits the existing kb, whether its citations resolve,
whether it duplicates something already filed, and whether it contradicts
an approved claim. those signals already exist in scattered form
(find_similar_on_propose, proposals._payload_block_reason) but nothing
surfaces them together as a ranked, explained view.

this adds an optional read-side triage pass over the pending queue:

• kb.triage_pending(proposal_ids=None) returns each pending proposal's
  model_dump plus a _meta.vouch_triage block: recommendation
  (approve / reject / needs-human, advisory only), score (0.0-1.0),
  signals (fit, citation_quality, duplication_risk,
  contradiction_risk, each with its own score + rationale), and a short
  rationale string.
• vouch triage [proposal-id...] mirrors it on the cli, with --json and
  --reverse.
• opt-in: disabled unless triage.enabled: true is set in
  .vouch/config.yaml; per-signal triage.weights are configurable.

review-gate scope

read-only by construction — this is the load-bearing property the north
star in CLAUDE.md calls out. the pass never calls proposals.approve,
proposals.reject, store.put_*, or store.move_proposal_to_decided; a
human still calls kb.approve / kb.reject. recommendation is an
advisory string nothing else consumes.

• citation_quality reuses proposals._payload_block_reason (the same
  dangling-ref / invalid-payload gate check_approvable uses).
• duplication_risk reuses the propose-time embedding path
  (embeddings.similarity.find_similar_on_propose) for claims, and
  degrades to a difflib text-similarity heuristic when no embedder is
  registered (base install, no [embeddings] extra) — the block shape
  stays the same either way.
• fit runs its own lower-threshold embedding search
  (index_db.search_embedding) rather than reusing the near-duplicate-only
  hits from find_similar_on_propose — reusing those directly would let a
  literal duplicate's high "fit" score cancel out its own
  duplication_risk penalty in the composite.
• contradiction_risk looks for topically-related approved claims that
  share an entity with the proposal but disagree on a simple negation-word
  signal (heuristic, advisory only — same caveats as the other signals).

registered at all four kb.* surface sites: server.py (@mcp.tool()),
jsonl_server.py (_h_triage_pending + HANDLERS), capabilities.py
(METHODS), and cli.py (vouch triage).

test plan

• tests/test_triage.py (25 tests): output shape, the no-write
  invariant (pending proposals stay pending, nothing approved/rejected/
  created), the disabled-by-default opt-in gate, citation_quality
  forcing reject on a dangling-ref proposal, duplication_risk on both
  the heuristic and embedding backends (--backend heuristic config
  override too), fit's entity-overlap + topical scoring, contradiction_risk's
  polarity-conflict heuristic, proposal_ids filtering, config/weights
  plumbing, and cli / jsonl wiring
• .venv/bin/python -m pytest tests/ -q --ignore=tests/embeddings — full
  suite green apart from 7 pre-existing Windows-only failures (verified
  identical on a clean main checkout — os.getuid(), symlink
  privilege, and path-separator assertions) and 2 pre-existing hangs in
  test_http_server*.py (also reproduce on a clean checkout, unrelated
  to this change)
• .venv/bin/python -m mypy src — clean (same 2 pre-existing Windows/
  missing-stub errors on a clean checkout)
• .venv/bin/python -m ruff check src tests — clean

Summary by CodeRabbit

• New Features

  • Added advisory triage scoring for pending items, with a score, recommendation, and rationale shown in the app, CLI, and API responses.
  • Added support for viewing triage results in JSON and ranked human-readable output.
  • Triage can be enabled through configuration and includes a fallback when advanced similarity support isn’t available.

• Tests

  • Expanded automated coverage for triage behavior, output format, configuration, and command/API wiring.